<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- deploying-android.qdoc -->
  <title>Deploying Applications to Android Devices | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Deploying Applications to Android Devices</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-deployment.html" />
  <link rel="next" href="creator-deployment-embedded-linux.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-deployment.html">Deploying to Devices</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-deployment-embedded-linux.html">Deploying Applications to Embedded Linux Devices</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#using-ministro-to-install-qt-libraries">Using Ministro to Install Qt Libraries</a></li>
<li class="level1"><a href="#packaging-applications">Packaging Applications</a></li>
<li class="level2"><a href="#specifying-settings-for-packages">Specifying Settings for Packages</a></li>
<li class="level1"><a href="#installing-ministro">Installing Ministro</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Deploying Applications to Android Devices</h1>
<span class="subtitle"></span>
<!-- $$$creator-deploying-android.html-description -->
<div class="descr"> <a name="details"></a>
<p>On Android, applications are distributed in specially structured types of ZIP packages called Application Packages (APK) or Android App Bundles (AAB). APK files can be downloaded to and executed on a device, whereas AAB is intended to be interpreted by the Google Play store and is used to generate APK files.</p>
<p><a href="http://doc.qt.io/qt-5/android.html">Qt for Android</a> has binaries for armv7a, arm64-v8a, x86, and x86-64. To support several different ABIs in your application, build an AAB that contains binaries for each of the ABIs. The Google Play store uses the AAB to generate optimized APK packages for the devices issuing the download request and automatically signs them with your publisher key.</p>
<p>Qt Creator supports the following methods of deployment for Android applications:</p>
<ul>
<li>As a stand-alone, distributable application package (APK).</li>
<li>As a minimal APK that contains a dependency to the Ministro tool. The Ministro tool downloads the necessary Qt libraries from a repository of your choice.</li>
<li>Since Qt 5.14.0, as an app bundle (AAB), intended for distribution in the Google Play store.</li>
</ul>
<p>To specify settings for application packages, select <b>Projects</b> &gt; <b>Build Android APK</b> &gt; <b>Details</b>.</p>
<p>For more information about options that you have for running applications, see <a href="creator-run-settings.html#specifying-run-settings-for-android-devices">Specifying Run Settings for Android Devices</a>.</p>
<a name="using-ministro-to-install-qt-libraries"></a>
<h2 id="using-ministro-to-install-qt-libraries">Using Ministro to Install Qt Libraries</h2>
<p>To minimize the size of your APK, you can package the application with an external dependency called Ministro. If a user downloads your application, and it is the first application on their device to depend on Ministro, they are asked to install Ministro before they can run your application.</p>
<p>Ministro serves as a central repository for Qt libraries. This enables several applications to share the libraries, which only need to be installed once. To use this deployment method, you must set up a repository for the libraries that you want to distribute. To specify the repository URL, edit the file <code>android/res/values/libs.xml</code>, which is created by Qt Creator.</p>
<p>To use Ministro to install the Qt libraries, select the <b>Use Ministro service to install Qt</b> option.</p>
<a name="packaging-applications"></a>
<h2 id="packaging-applications">Packaging Applications</h2>
<p>Because bundling applications as APK packages is not trivial, Qt 5 provides a deployment tool called <code>androiddeployqt</code>. When you deploy an application using a <b>Qt for Android Kit</b>, Qt Creator uses the <code>androiddeployqt</code> tool to create the necessary files and to bundle them into an APK:</p>
<ul>
<li>Java files, which serve as the entry point into your application and that automatically load Qt and execute the native code in your application.</li>
<li>AndroidManifest.xml, which provides meta-information about your application.</li>
<li>Other XML files, which specify the dependencies of your application.</li>
<li>Resource files.</li>
<li>Libraries and QML files, which can be included in the project depending on the deployment method that you select.</li>
<li>Gradle wrappers that are needed to download and use Gradle.</li>
<li>Gradle script that is needed by Java IDEs, such as Android Studio. It allows the user to extend the Java part without copying our Java sources. It also allows the IDEs to provide code completion, syntax highlighting, and so on.</li>
</ul>
<p>The Gradle wrappers and scripts are bundled only if you use Gradle to build the application packages. For more information, see <a href="creator-developing-android.html">Connecting Android Devices</a>.</p>
<p>To view the packages that the <code>androiddeployqt</code> tool created, select the <b>Open package location after build</b> check box.</p>
<p>The packages are deployed on the connected Android devices. To switch the device used as a default device for the selected kit, select <b>Projects</b> &gt; <b>Run</b> &gt; <b>Reset Default Devices</b>. The setting applies until you restart Qt Creator. For more information, see <a href="creator-developing-android.html#selecting-android-devices">Selecting Android Devices</a>.</p>
<p>For more information about the <code>androiddeployqt</code> tool, see <a href="http://doc.qt.io/qt-5/deployment-android.html">Deploying an Application on Android</a>.</p>
<a name="specifying-settings-for-packages"></a>
<h3 id="specifying-settings-for-packages">Specifying Settings for Packages</h3>
<p>You can specify settings for the <code>androiddeployqt</code> tool in Qt Creator and in the project .pro file. To specify settings in Qt Creator, select <b>Projects</b> &gt; <b>Build Android APK</b> &gt; <b>Details</b>.</p>
<p class="centerAlign"><img src="images/qtcreator-android-deploy-configurations.png" alt="&quot;Deploy configurations&quot;" /></p><p>The anddroiddeployqt tool uses the information in the project .pro file to create APKs. For more information about the qmake variables that you can set in the .pro file to tailor the APK, see <a href="http://doc.qt.io/qt-5/deployment-android.html">Deploying an Application on Android</a>.</p>
<p>You can view information about what the anddroiddeployqt tool is doing in the <b>Compile Output</b> pane. To view additional information, select the <b>Verbose output</b> check box.</p>
<a name="building-aabs"></a>
<h4 id="building-aabs">Building AABs</h4>
<p>For testing the application locally, use the APK format, because the package can be uploaded directly to the device and run. For distribution to the Google Play store, create an AAB by selecting the <b>Build .aab (Android App Bundle)</b> check box.</p>
<p>When building with CMake, you can select the ABIs to build the application for in the <b>CMake</b> settings:</p>
<p class="centerAlign"><img src="images/qtcreator-android-cmake-settings.png" alt="&quot;CMake settings for building AABs&quot;" /></p><p>When building with qmake, you can select the ABIs in the <b>ABIs</b> field in the <b>Build Steps</b>:</p>
<p class="centerAlign"><img src="images/qtcreator-android-build-steps.png" alt="&quot;Android Build Steps&quot;" /></p><a name="selecting-api-level"></a>
<h4 id="selecting-api-level">Selecting API Level</h4>
<p>In the <b>Android build SDK</b> field, you can select the API level to use for building the application. Usually, you should select the newest API level available.</p>
<p>This field does not specify the minimum supported API level nor the target API level, which you can specify in the Android manifest file. For more information about Android API levels, see <a href="http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API Level?</a>.</p>
<a name="signing-android-packages"></a>
<h4 id="signing-android-packages">Signing Android Packages</h4>
<p>To publish your application, you must sign it by using a <i>public-private key pair</i> that consists of a <i>certificate</i> and a corresponding <i>private key</i> and is identified by an <i>alias</i>. The key pair is used to verify that the future versions of your application are actually created by you.</p>
<p><b>Warning:</b> Keep the key pair in a safe place and take back up copies, because you cannot update the application if you lose the key pair.</p>
<p>You can use Qt Creator to generate a keystore and a <i>self-signed</i> certificate. The generated certificate has the structure of an X.509 v3 digital certificate. It contains information about the version, serial number, and validity period of the certificate, the ID of the algorithm that is used to encrypt the data, the organization that issued the certificate, and the <i>subject</i> (owner) of the certificate. In case of a self-signed certificate, the issuer and owner of the certificate are the same. In addition, the certificate contains information about the algorithm that is used to sign the certificate, as well as the signature of the certificate.</p>
<p>The keystore is protected by a password. In addition, you can protect each alias with its individual password.</p>
<p>When you sign an Android application, you must select a keystore that contains certificates and a certificate alias from the keystore. The public key (certificate) for the alias is embedded into the APK during signing.</p>
<p>To create a keystore and a self-signed certificate:</p>
<ol class="1" type="1"><li>In the <b>Keystore</b> field, select <b>Create</b> to create a new keystore that contains one key pair in the <b>Create Keystore and a Certificate</b> dialog:<p class="centerAlign"><img src="images/qtcreator-android-certificate.png" alt="" /></p></li>
<li>In the <b>Keystore</b> group, enter a password to protect the keystore.</li>
<li>In the <b>Certificate</b> group, specify the key size and validity period of the certificate. You can specify a separate password to protect the key pair or use the keystore password.</li>
<li>In the <b>Certificate Distinguished Names</b> group, enter information about yourself and your company or organization that identifies the issuer and the owner of the key pair.</li>
<li>Select <b>Save</b>.</li>
<li>In the <b>Keystore File Name</b> dialog, enter a name for the keystore and select a location for it.</li>
<li>In the <b>Keystore</b> dialog, enter the keystore password to create the key pair in the keystore.</li>
</ol>
<p>To sign an Android package by using a key pair, specify settings in the <b>Sign package</b> group:</p>
<ol class="1" type="1"><li>In the <b>Keystore</b> field, select <b>Choose</b> to select an existing keystore.</li>
<li>In the <b>Certificate alias</b> field, select an alias from the list of key pairs that the keystore contains.</li>
<li>Select the <b>Sign package</b> check box to use the alias to sign the Android package.</li>
</ol>
<a name="adding-external-libraries"></a>
<h4 id="adding-external-libraries">Adding External Libraries</h4>
<p>Qt Creator automatically detects which Qt libraries the application uses and adds them as dependencies. If the application needs external libraries, specify them in the <b>Additional Libraries</b> field. The libraries are copied into your application's library folder and loaded on startup.</p>
<p>For example, to enable OpenSSL in your application, add the paths to the required <code>libssl.so</code> and <code>libcrypto.so</code> libraries to the <b>Additional Libraries</b> field.</p>
<a name="editing-manifest-files"></a>
<h4 id="editing-manifest-files">Editing Manifest Files</h4>
<p>You can use the qmake variables to specify all the settings you need for the <code>androiddeployqt</code> tool and you do not need an Android manifest file until you want to publish the package in an application store. To specify additional settings for APK packages, you can create an Android manifest file and edit it in Qt Creator. Select <b>Create Templates</b> to create the file and to open it in the Android Manifest Editor.</p>
<p class="centerAlign"><img src="images/qtcreator-android-manifest-editor.png" alt="&quot;Android Manifest Editor&quot;" /></p><ol class="1" type="1"><li>In the <b>Package name</b> field, enter a package name for the application. The application is launched by an automatically generated Java launcher that is packaged with the application into an Android package (.apk). For more information, see <a href="http://developer.android.com/guide/components/fundamentals.html">Android Application Fundamentals</a>.</li>
<li>You can specify an internal version number for the package in the <b>Version code</b> field. It is used to determine whether one version of the application is more recent than another. In the <b>Version name</b> field, specify the version number that is shown to users.</li>
<li>In the <b>Minimum required SDK</b> field, select the minimum API level required to run the application. The minimum supported API level is android-9. Qt Creator does not allow you to select an API level that the Qt version specified for the kit does not support.</li>
<li>In the <b>Target SDK</b> field, select the targeted API level of the application. This affects the activation of some compatibility features in the OS. The value used by the <code>androiddeployqt</code> tool by default is 14, which means that the overflow button in the system navigation bar will not be enabled by default.</li>
<li>In the <b>Application</b> group, you can give the application a name and select an icon for it. The three icon fields can contain different versions of the icon with low, medium, and high DPI values, from left to right. You can also give an activity a name and select the activity to run.</li>
<li>In the <b>Permissions</b> field, you can specify the permissions that your application needs. Users are asked to grant the permissions when they install the application. Android OS then grants the application access to the appropriate data and features.</li>
<li>Select the <b>Include default permissions for Qt modules</b> and <b>Include default features for Qt modules</b> check boxes to add the permissions needed by Qt libraries.</li>
<li>To add permissions, select them in the list, and then select <b>Add</b>.</li>
</ol>
<p>Select the <b>XML Source</b> tab to edit the file in XML format.</p>
<a name="installing-ministro"></a>
<h2 id="installing-ministro">Installing Ministro</h2>
<p>The easiest way to install Ministro is to do it on the device via Google Play. When you run the application for the first time, a dialog pops up and guides you through the installation.</p>
<p>To use Qt Creator to install Ministro, you must first download the Ministro .apk from the Google Market or from the <a href="http://necessitas.kde.org/necessitas/ministro.php">Ministro</a> home page.</p>
<p>Then select <b>Projects</b> &gt; <b>Run</b> &gt; <b>Install Ministro from APK</b>.</p>
<p>You can use this option also to install any Android package (.apk).</p>
<p>You can use this option to install applications on an Android Virtual Device (AVD).</p>
</div>
<!-- @@@creator-deploying-android.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-deployment.html">Deploying to Devices</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-deployment-embedded-linux.html">Deploying Applications to Embedded Linux Devices</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
